Improve Docker run documentation with persistent volumes and .env clarification#18
Merged
Conversation
Combine the persistent home-directory example with the named cache volumes to match common usage, and add a table explaining why .env is referenced twice (--env-file injects vars; -v mounts the file for MCP_ENV_FILE and the Secrets UI). Note both flags take the local host path, that the file must exist, and that MCP_ENV_FILE already defaults to /app/.env in the image.
Keep the container around across stops/reboots; the named volumes already handle persistence. MCP_ENV_FILE need not be passed explicitly since the image defaults it to /app/.env.
Include -e MCP_ENV_FILE=/app/.env in the recommended run command so users know the setting exists, and note that it's optional since the image already defaults it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR significantly expands and clarifies the Docker deployment documentation, particularly around persistent storage volumes and the dual-purpose
.envfile configuration. The changes provide users with a more complete, production-ready command and better explain the reasoning behind each flag.Key Changes
mcpproxy-files,mcpproxy-repos,mcpproxy-cache,mcpproxy-npm,mcpproxy-uv-tools,mcpproxy-mcp-auth) for better persistence across container restarts-e MCP_ENV_FILE=/app/.envfrom the command since the image already defaults to this value--rmflag to automatically clean up stopped containers.envconfiguration table explaining the two different ways the.envfile is referenced and why each is necessary:--env-filefor Docker to inject environment variables at startup-vmount for the proxy and web UI to read/write the file live$HOMEis used instead of~MCP_ENV_FILEmcpproxy-mcp-authvolume for OAuth token persistence and callback port mapping guidanceNotable Details
.env: environment variable injection vs. live file accesshttps://claude.ai/code/session_01BgJ5hooXNfxc2SKQVir2nf